Got you. Let’s lock the design first, then walk a very concrete implementation plan.

---

## 1. Design baseline

### 1.1 What is actually enforced vs just marketing

| Area                      | Enforced in backend                                                                                               | Marketing only / derived text                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Sites per account         | Yes, via `Plan.max_sites` and `Site.get_max_sectors_limit()` for industries/sectors                               | Text on pricing page rephrases this, no extra logic |
| Users per account         | Yes, via per plan user limit if present in Plan model (or enforced through Account → User count)                  | Pricing shows same number, no separate enforcement  |
| Credits per month         | Yes, `Plan.included_credits` / `Plan.get_effective_credits_per_month()` → `Account.credits` on signup and renewal | Words per month etc derived from credits only       |
| Payment method            | Yes, new `payment_method` on Account and Subscription (stripe, paypal, bank_transfer)                             | UI labels like “Bank transfer” or “Coming soon”     |
| Keywords, clusters, ideas | Not enforced for now, only advisory copy                                                                          | Keep in pricing copy, treat as soft guidance        |
| Words per month           | Not enforced directly                                                                                             | Approx = credits * X words, shown only on frontend  |
| Daily content tasks       | Not enforced directly                                                                                             | Approx, shown only on frontend                      |
| Images per month          | Optional: either map to credits or leave as copy                                                                  | Pricing text only for now                           |

Decision: backend hard limits are Sites, (Industries/Sectors), Users, Credits. Everything else is just marketing descriptions driven from those hard limits.

---

## 2. Target user flows (one view)

### 2.1 High level text diagram

```text
Pricing page (marketing)
  → Choose plan (Starter / Growth / Scale)
  → Click "Start" → App Register (with plan_id preselected)
Register
  → POST /api/v1/auth/register/ with plan_id + payment_method=bank_transfer
  → Create User + Account(plan) + Subscription(payment_method, status='pending_payment')
  → Seed Account.credits = plan.get_effective_credits_per_month()
  → User can log in and use app while account.status in ['trial', 'active', 'pending_payment'] if you allow pre-payment use

App usage (monthly)
  → Login → JWT → AccountContextMiddleware sets request.account
  → User works in Planner / Writer
  → Every AI call:
       - CreditService.check_credits()
       - AICore runs model
       - CreditService.deduct_credits_for_operation()

Renewal
  → Admin confirms bank transfer for next period
  → Or Stripe webhook in future
  → Subscription period dates updated
  → Account.credits reset to plan monthly credits
  → Account.status set to 'active'

Expiry / non payment
  → Subscription.status becomes 'past_due'/'canceled'
  → Account.status set to 'suspended'
  → Login / AI calls blocked with clear message
```

---

## 3. Phase A – Plans and pricing alignment

### A1. Make Plan the single source of truth for limits

**Implementation**

* In `Plan` model ensure we have at least: `slug`, `name`, `price`, `billing_cycle`, `included_credits`, `max_sites`, `max_users`, `max_industries` (or current field names).

* Add helper: `Plan.to_public_dict()` that returns exactly what pricing needs:

  * `name`, `slug`, `price`, `billing_cycle`
  * `max_sites`, `max_users`, `included_credits`
  * optional: `tagline`, `recommended`, `order_index` (pure marketing fields stored on Plan to avoid hardcoded frontend).

* Update `/api/v1/auth/plans/` to return only these fields plus computed soft fields:

  * `approx_words_per_month = included_credits * WORDS_PER_CREDIT` (constant, eg 120).
  * `approx_images_per_month = included_credits / CREDITS_PER_IMAGE` (if you want).

**Verification**

* Hit `GET /api/v1/auth/plans/` and confirm:

  * Each plan matches DB row and has only canonical hard limit fields plus derived estimates.
  * No legacy fields leaking like “keywords_limit” unless they truly exist.

* Update pricing page to build cards from this response instead of static JSON.

### A2. Simplify pricing UI to reflect hard limits

**Implementation**

* On `igny8.com/pricing`:

  * Show for each plan:

    * Sites, users, AI credits per month (clear).
    * A line like “Up to ~120K AI generated words per month” using API derived field.
    * Keep keywords/clusters/ideas as descriptive bullet points, but not used anywhere in backend.

* Change CTA text from “Start free trial” to “Get started” or keep label but functionally treat as plan signup.

**Verification**

* Disable JS and verify pricing still renders correct values from API.
* Check for each plan: numbers on page match `Plan` entries and included_credits.

---

## 4. Phase B – Signup, subscription and payment methods

### B1. Extend models for payment_method and external_payment_id

**Implementation**

* Add migrations as per audit:

  * `Account.payment_method` (choices: stripe, paypal, bank_transfer, default stripe).
  * `Subscription.payment_method` same choices.
  * `Subscription.external_payment_id` nullable.
  * Make `stripe_subscription_id` nullable and drop unique if necessary.

* Backfill existing rows: set `payment_method='stripe'` where `stripe_subscription_id` is not null.

**Verification**

* Run migrations in staging:

  * Confirm existing subscriptions untouched but now have `payment_method='stripe'`.
  * New columns visible in Django admin.

### B2. Wire pricing CTA to register with plan

**Implementation**

* Pricing card button:

  * On click, route to `app.igny8.com/register?plan=starter` etc.

* Register page in app:

  * On mount, call `/api/v1/auth/plans/` and validate that `plan` query param is a valid `slug`.
  * Show selected plan summary in the form.

* Registration form posts:

  * `POST /api/v1/auth/register/` with body:

    ```json
    {
      "email": "...",
      "password": "...",
      "account_name": "...",
      "plan_slug": "starter",
      "payment_method": "bank_transfer"
    }
    ```

  * Backend resolves `plan_slug` to `Plan`, sets on Account and Subscription, sets `payment_method`, sets `Subscription.status='pending_payment'` and `Account.status='pending_payment'` or `trial`, and seeds `Account.credits = plan.get_effective_credits_per_month()`.

* Wrap creation in a database transaction as per audit. 

**Verification**

* From pricing go through full register flow:

  * Check DB: new User, Account with correct Plan, Subscription linked, `payment_method='bank_transfer'`, credits set to plan value.
  * Decode JWT after login and verify `account_id` matches created account and account.status is as expected.

### B3. Bank transfer confirmation flow

**Implementation**

* Create admin endpoint `POST /api/v1/billing/confirm-bank-transfer/`:

  * Guarded by `IsAdminOrOwner` or separate `IsStaffAdmin`.
  * Accepts `subscription_id`, `external_payment_id`, amount, payer details, optional proof URL.
  * Inside a transaction:

    * Validate subscription belongs to account.
    * Set `Subscription.payment_method='bank_transfer'`, `external_payment_id=...`, `status='active'`, and new `current_period_start` and `current_period_end`.
    * Set `Account.status='active'`.
    * Reset `Account.credits = plan.get_effective_credits_per_month()` and create a `CreditTransaction` log entry.

**Verification**

* In staging, create an account via bank transfer path, then hit admin endpoint:

  * Confirm status flips from pending to active.
  * Credits reset correctly.
  * User can login and use AI features without seeing payment required errors.

---

## 5. Phase C – Auth, tenancy and API key correctness

### C1. Central account+plan validation

**Implementation**

* Extract helper `validate_account_and_plan(account)` from `AccountContextMiddleware`. 

  * Checks:

    * `account` exists and not deleted.
    * `account.status in allowed set` (trial, active, pending_payment if you allow usage).
    * `account.plan` exists and plan active.

* Use this helper:

  * In middleware for JWT/session requests.
  * In `APIKeyAuthentication.authenticate()` for API key requests.

**Verification**

* Test matrix:

  * Account active → both JWT and API key get access.
  * Account suspended or plan inactive → both JWT and API key requests receive consistent 402/403.

### C2. Throttling and tenant scoping

**Implementation**

* Update `DebugScopedRateThrottle`:

  * Keyed by `(scope, account.id)` instead of user only.
  * Only bypass when `DEBUG=True` or a special flag is set. 

**Verification**

* Use a script to hit AI endpoints many times:

  * Same account should start getting 429 after configured limit.
  * Different accounts are throttled independently.

---

## 6. Phase D – Credits as single limiting mechanism

### D1. Standardize credit operations

**Implementation**

* In `CreditService` define per operation costs:

  * `CLUSTER_COST_PER_KEYWORD`, `IDEA_COST_PER_CLUSTER`, `CONTENT_COST_PER_1K_TOKENS`, `IMAGE_COST_PER_IMAGE`, etc.

* For each AI entry point in Planner and Writer:

  * Before calling any AI engine, call `CreditService.check_credits(account, operation_type, units)` and fail fast with a friendly error if credits insufficient.
  * After success, call `deduct_credits_for_operation`.

* Ensure `AIEngine.execute` never calls external API without passing through CreditService. 

**Verification**

* With a test account:

  * Set credits small (for example 10 credits).
  * Run a sequence of operations until credits exactly hit zero.
  * Verify next AI attempt fails with “not enough credits” and no external API call is made.

### D2. Monthly credits reset on renewal

**Implementation**

* In renewal handler (Stripe webhook or bank transfer confirm):

  * Always:

    * Set `Account.credits = plan.get_effective_credits_per_month()` as new monthly allowance (no rollover), or apply your chosen policy.

**Verification**

* Manipulate subscription dates to simulate new period, run renewal handler:

  * Compare previous credits to new credits and confirm reset logic is correct.

---

## 7. Phase E – End to end user flows and QA checklists

For each flow from Final_Flow_Tenancy plus the new marketing connection, create a short verification table. Example:

### E1. Flow P – Pricing to first login

| Step | Action                  | Expected backend state                                                                                                  |
| ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| P1   | Open pricing page       | `GET /auth/plans/` called, numbers match Plan rows                                                                      |
| P2   | Click “Start” on Growth | Browser navigates to `/register?plan=growth`                                                                            |
| P3   | Submit registration     | User, Account(plan=growth), Subscription(payment_method='bank_transfer', status='pending_payment'), Account.credits set |
| P4   | Login                   | JWT issued, `request.account` set to new account                                                                        |
| P5   | Visit Sites page        | Only default site or none, request.account matches account.id                                                           |

### E2. Flow C – Credits and AI usage

| Step | Action                             | Expected result                                                                                  |
| ---- | ---------------------------------- | ------------------------------------------------------------------------------------------------ |
| C1   | Note current Account.credits       | Shows value N from Plan                                                                          |
| C2   | Run auto cluster for small batch   | Credits drop by expected amount, clusters created                                                |
| C3   | Generate content draft             | Credits drop again, Content row created                                                          |
| C4   | Keep triggering until credits zero | Last allowed request succeeds, next request returns “insufficient credits” without external call |

### E3. Flow R – Renewal

| Step | Action                                  | Expected result                                                                    |
| ---- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| R1   | Admin confirms next month bank transfer | Subscription dates advanced, status active, Account.credits reset to monthly quota |
| R2   | User logs in and runs AI                | Requests succeed and credits decrement from new monthly total                      |

### E4. Flow X – Expiry

| Step | Action                                                            | Expected result                                                  |
| ---- | ----------------------------------------------------------------- | ---------------------------------------------------------------- |
| X1   | Set Subscription.status='past_due' and Account.status='suspended' | Login shows “Active subscription required”, AI endpoints blocked |
| X2   | Confirm payment again                                             | Account.status back to active, login and AI work                 |

---

## 8. Phase F – Tests and CI

Wrap everything with tests so this stays correct.

* Unit tests for:

  * Plan API response shape vs Plan model.
  * Registration transaction: no partial user or account on failure.
  * validate_account_and_plan for different statuses.
  * CreditService check and deduct behavior for each operation.

* Integration tests for:

  * Pricing → register → login → run AI until credits exhausted.
  * Bank transfer confirmation and renewal.
  * API key access for active vs suspended accounts.

Once these phases are implemented and the flow tables all pass in staging, you have a fully connected, credit based, monthly subscription system where marketing, signup, tenancy, billing, and AI usage all match the single Final_Flow_Tenancy spec plus the two audits.