[FEATURE] Implement Hybrid Billing System (Subscription + Extra Credits)

[sanaderi]

We are introducing a hybrid billing system that combines recurring subscriptions with optional one-time credit purchases.

Users will receive credits through their active subscription and can also buy additional credits whenever needed.

All billing actions are managed through Stripe and synchronized via backend events.

---

Goals

1. Subscription-Based Credits

Each time a subscription is successfully renewed:

• Existing subscription credits are reset
• New credits are assigned based on the selected plan

Example plans:

• Basic → 1000 credits per month
• Pro → 4000 credits per 3 month
• Premium → 9000 credits per 9 month

---

2. Extra Credit Purchases

Users can purchase additional credits independently of their subscription.

• Credits are added immediately after successful payment
• These credits are separate from subscription credits
• They do not replace or reset existing subscription credits

Example packages:

• 1000 credits → $5
• 5000 credits → $20

---

3. Unified Payment Flow

All payment actions (subscription and extra credits) are handled through a single billing entry point, differentiated by the selected purchase type.

---

Credit System

Credit Sources

• Subscription Credits (refilled each billing cycle)
• Extra Credits (purchased separately)

Total Available Credits

Total Credits = Subscription Credits + Extra Credits

---

Billing Rules

• Subscription renewal resets and refills subscription credits
• Extra credits are always added on top of existing balance
• Credits are deducted based on user usage across the platform

---

Credit Exhaustion Behavior

If a user runs out of credits:

• Access to credit-based features is restricted or paused
• The user can:
  • Wait for the next subscription renewal
  • Purchase extra credits immediately

---

System Principles

• Billing state is always synchronized with Stripe
• Subscription renewal is the only point where subscription credits reset
• Credit changes are always reflected consistently across the system

---

Future Improvements

• Optional credit expiration rules for subscription credits
• Grace period after subscription cancellation
• Upgrade and downgrade handling between plans
• Full tracking of credit usage history

[victory7]

Good idea and plan. What do you think about considering monthly and annual recurring options with a off percent on annual?

For example having three plans, each one has its own available features and limitations with a fixed idea of choosing between monthly or annual subscription. This is more familiar for most users instead of having one month, 3 months, 9 months plans.

So for example it could be something like this:
Basic → 1000 credits per month
Pro → 2500 credits per month
Premium → 7000 credits per month

[sanaderi]

I agree. Monthly and annual subscriptions are generally more familiar to users and make plan comparison much easier.