Implement WHMCS Addon Dashboard with API for stats and integrate billing provider logic

docs/billing/providers.md

@@ -0,0 +1,43 @@
+# Billing providers
+
+GameCloud supports three billing modes via `BILLING_PROVIDER`:
+
+| Provider | Use case | Credit wallet |
+|----------|----------|---------------|
+| `internal` | Dev / free tier | Required for start |
+| `whmcs` | **Production default** | Bypassed — WHMCS bills customers |
+| `stripe` | Optional fallback without WHMCS | Bypassed — extend webhook handler |
+
+## WHMCS (recommended)
+
+```env
+BILLING_PROVIDER=whmcs
+WHMCS_INTEGRATION_ID=your-integration-id
+WHMCS_API_SECRET=your-secret
+```
+
+Commercial lifecycle (orders, invoices, suspend, usage metrics) runs entirely in WHMCS. GameCloud enforces `billingSuspendedAt` from WHMCS API calls.
+
+## Internal (development)
+
+```env
+BILLING_PROVIDER=internal
+```
+
+Uses the credit wallet and usage metering from Phase 7. Suitable for local development and standalone free tier.
+
+## Stripe (optional fallback)
+
+```env
+BILLING_PROVIDER=stripe
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Webhook endpoint: `POST /api/v1/webhooks/stripe`
+
+When `BILLING_PROVIDER` is not `stripe`, webhooks return `{ received: true, mode: 'ignored' }` without side effects.
+
+The current implementation verifies signatures and logs events idempotently. Extend `StripeWebhookService` to map Stripe customers to GameCloud users if you deploy without WHMCS.
+
+**Do not enable Stripe and WHMCS billing simultaneously** — choose one commercial system of record.