feat: add production-grade React SDK extensions for Pi Network apps

[Clawue884]

🚀 Overview

This PR significantly extends pi-sdk-react with a production-grade, lifecycle-aware React SDK architecture designed for real-world Pi Network applications.

The goal is not to modify Pi Network protocol behavior, but to provide a robust application-layer SDK that improves developer ergonomics, safety, and scalability while remaining fully aligned with the official Pi Browser SDK (window.Pi).

---

✨ What’s Included

🧩 Core Architecture

• Introduced a clear application-layer SDK structure
• Centralized Pi SDK readiness detection
• Typed error model (PiSdkError, PiSdkErrorCode)

🔐 Authentication & Connection

• usePiConnection() – shared readiness & connection state
• usePiAuth() – explicit authentication lifecycle (auth ≠ payment)

💸 Payment Lifecycle (Major Upgrade)

• usePiPayment() with full lifecycle state:
  • idle → pending → success / failed / cancelled
• Client-side payment validation
• Explicit error handling & transaction ID exposure

🌐 Backend Handshake Readiness

• usePiServerHandshake() hook to support proper server-side approval & completion flows (without violating Pi architecture)

🧠 Global Context (Optional)

• PiProvider for shared Pi readiness & user state
• Safe for Next.js App Router and CSR environments

🧪 Developer Experience

• Mock Pi SDK for local development & testing
• Ready-to-use UI components:
  • PiPayButton
  • PiAuthGuard

---

🏗️ Design Principles

• ✅ React-first, TypeScript-strict
• ✅ No protocol assumptions beyond official Pi SDK
• ✅ Application-layer only (not consensus / smart contracts)
• ✅ Framework-agnostic (Next.js, Vite, CRA compatible)
• ✅ Safe, explicit, and extensible

---

🔍 Scope & Compatibility

• Fully backward-compatible with existing pi-sdk-react usage
• Does not alter or wrap Pi Network core behavior
• Enhances SDK usability for:
  • Marketplaces
  • Games
  • Digital services
  • Subscription-based apps

---

📌 Notes

This PR is intended to help Pi app developers build real, production-ready applications with clearer patterns and safer defaults, while keeping Pi Network’s architectural boundaries intact.

Feedback and review are very welcome.