temproary docs uplaoded

v2/Live Docs on Server/igny8-app-docs/90-REFERENCE/BILLING-SYSTEM-MASTER.md

@@ -0,0 +1,114 @@
+# IGNY8 Billing System Master Document
+
+**Last Updated:** 2026-01-20
+
+> **Primary Reference:** For complete billing documentation, see [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
+
+This document provides a summary of the billing system implementation.
+
+---
+
+## 1) Core Principles
+
+- **Two-Pool Credit System:**
+  - `account.credits` = Plan credits (reset on renewal)
+  - `account.bonus_credits` = Purchased credits (NEVER expire, NEVER reset)
+- **Credit Usage Priority:** Plan credits used FIRST, bonus credits only when plan credits = 0
+- **No hardcoded products**: Plans, credit packages, and future add-ons are data-driven.
+- **Explicit invoice type**: `subscription`, `credit_package`, `addon`, `custom`.
+- **Correct crediting**:
+  - Subscription: reset plan credits to **full plan amount** on payment (bonus untouched)
+  - Credit package: add to **bonus_credits** only (never plan credits)
+- **Renewal Grace Period:** 7 days
+- **Credit Reset on Non-Payment:** 24 hours after renewal (Day +1), plan credits → 0
+- **Auditability**: Every credit change is recorded in `CreditTransaction`.
+
+---
+
+## 2) Two-Pool Credit System
+
+| Pool | Field | Source | Behavior |
+|------|-------|--------|----------|
+| Plan Credits | `account.credits` | Subscription plan | Reset to plan amount on renewal payment, reset to 0 if unpaid after 24h |
+| Bonus Credits | `account.bonus_credits` | Credit packages | NEVER expire, NEVER reset, only deducted after plan credits = 0 |
+
+### Credit Deduction Priority
+1. Deduct from `credits` (plan) first
+2. Only when `credits = 0`, deduct remainder from `bonus_credits`
+
+---
+
+## 3) Renewal Workflow (Simplified)
+
+### Stripe/PayPal (Auto-Pay) - Industry Standard
+- **No advance notice** (like Netflix, Spotify)
+- Day 0: Auto-charge attempt
+- If success: Receipt email + credits reset to plan amount
+- If failed: Retry notification, Stripe retries 4x over 7 days
+- Day +7: Expired if all retries fail
+
+### Bank Transfer (Manual)
+- **Day -3:** Invoice created + Email sent
+- **Day 0:** Renewal day reminder (if unpaid)
+- **Day +1:** Urgent reminder + credits reset to 0
+- **Day +7:** Subscription expired
+
+---
+
+## 4) Scheduled Tasks (Updated)
+
+| Task | Purpose | Schedule |
+|------|---------|----------|
+| `create_bank_transfer_invoices` | Invoice 3 days before (bank transfer only) | Daily 09:00 |
+| `process_subscription_renewals` | Auto-pay renewals (Stripe/PayPal) | Daily 00:05 |
+| `send_renewal_day_reminders` | Day 0 reminder (bank transfer) | Daily 10:00 |
+| `send_day_after_reminders` | Day +1 urgent reminder + credit reset | Daily 09:15 |
+| `check_expired_renewals` | Expire after 7-day grace | Daily 00:15 |
+| `send_credit_invoice_expiry_reminders` | Credit invoice reminder | Daily 09:30 |
+| `void_expired_credit_invoices` | Auto-void credit invoices (48h) | Daily 00:45 |
+
+---
+
+## 5) Invoice Types and Fulfillment
+
+| Invoice Type | Credits Action | Account Status |
+|--------------|----------------|----------------|
+| `subscription` | Reset plan credits to plan amount | Activate account + subscription |
+| `credit_package` | Add to **bonus_credits** | No status change |
+| `addon` | Provision entitlement | No status change |
+| `custom` | As specified | No status change |
+
+---
+
+## 6) Key Implementation Rules
+
+1. **Two pools:** `credits` (plan) + `bonus_credits` (purchased)
+2. **Deduction order:** Plan credits first, then bonus credits
+3. **Subscription payment:** Reset plan credits to full amount (bonus untouched)
+4. **Credit package payment:** Add to bonus_credits only
+5. **No payment 24h:** Plan credits → 0, bonus credits unchanged
+6. **Late payment:** Plan credits restored to full amount
+
+---
+
+## 7) Quick Reference
+
+### Payment Method by Country
+| Country | Stripe | PayPal | Bank Transfer |
+|---------|--------|--------|---------------|
+| Pakistan (PK) | ✅ | ❌ | ✅ |
+| Others | ✅ | ✅ | ❌ |
+
+### Credit Reset Summary
+| Event | Plan Credits | Bonus Credits |
+|-------|--------------|---------------|
+| Payment success | Reset to plan amount | No change |
+| No payment (24h) | Reset to 0 | No change |
+| Late payment | Reset to plan amount | No change |
+
+---
+
+## References
+
+- Complete Documentation: [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
+- Payment Gateways: [PAYMENT-SYSTEM.md](PAYMENT-SYSTEM.md)