Organize planning documents and update README structure

- Created a new `docs/planning/` directory to better organize architecture and implementation planning documents.
- Moved existing planning documents into the new directory for improved accessibility.
- Updated `README.md` to reflect the new document structure and added references to the organized planning documents.
- Enhanced overall documentation management for easier navigation and maintenance.

docs/planning/sample-usage-limits-credit-system

@@ -0,0 +1,124 @@
+# Unified Credit-Based Usage System — Instructions for Cursor
+
+## Objective
+Transition IGNY8 from a limit-based subscription model to a fully credit-driven usage model.  
+Every feature is unlocked for all paid users, and only credits determine how much the platform can be used.
+
+---
+
+## 1. Core Principle
+Remove all numerical limits tied to subscription plans.  
+Examples of limits that must no longer exist:
+
+- Number of keywords allowed  
+- Number of clusters  
+- Number of content ideas  
+- Daily or monthly content tasks  
+- Monthly word count  
+- Image generation limits  
+- Site limits  
+- User limits  
+- Any plan-based feature restrictions  
+
+The only limiter in the entire system should be **credits**.
+
+---
+
+## 2. Purpose of Subscription Plans
+Plans should no longer define usage capacity.  
+Plans only define:
+
+- Monthly credits added to the account  
+- Support and onboarding level  
+- Billing cycle (monthly or yearly)
+
+Every paid user gets full access to all features without restrictions.
+
+---
+
+## 3. Credit Economy
+Every system action should consume a defined number of credits.  
+The values can be adjusted later, but the mechanism must be universal.
+
+Example conceptual structure:
+
+- One clustering request consumes a small number of credits  
+- One idea generation request consumes more credits  
+- Content generation consumes credits based on word count  
+- Image generation consumes credits per image  
+- Optimization consumes credits per thousand words  
+- Linking operations consume a fixed number of credits  
+
+Credits should be deducted at the moment the action is initiated.
+
+---
+
+## 4. System Behavior
+Cursor should apply these global rules:
+
+- If the account has enough credits, the action proceeds  
+- If credits are insufficient, the system shows a clear warning and does not run the action  
+- All features remain available, but actions require credits  
+- Credit consumption must be tracked and logged for transparency  
+- Credit usage must be consistent across all modules  
+
+This ensures that usage is pay-as-you-go within the subscription credit budget.
+
+---
+
+## 5. Removal of Old Logic
+All of the following must be removed from the system:
+
+- Any checks for keyword count  
+- Any maximum allowed clusters  
+- Any caps on ideas  
+- Any daily task limits  
+- Any monthly generation limits  
+- Any image generation limits  
+- Any limits based on the user’s plan  
+- Any feature locking based on plan tier  
+
+The platform should feel “unlimited,” with only credit balance controlling usage.
+
+---
+
+## 6. Frontend Adjustments
+On the interface:
+
+- Remove UI elements showing limits  
+- Replace them with a simple display of remaining credits  
+- Show estimated credit cost before performing any action  
+- If credits are insufficient, display a clear prompt to buy more credits  
+- All features must appear unlocked and available  
+
+The user should understand that only credits restrict their usage, not the plan.
+
+---
+
+## 7. Billing and Top-ups
+Plans supply monthly credits, but users should be able to purchase extra credits anytime.  
+The system must support:
+
+- Monthly credit replenishment  
+- On-demand credit top-ups  
+- Tracking of credit usage history  
+- Notifications when credits run low  
+
+This ensures consistent monetization and scalability.
+
+---
+
+## 8. Guiding Principle for Cursor
+Cursor must treat **credits as the universal currency of usage**, and remove every other form of operational restriction.
+
+The product becomes:
+
+- Simpler for users  
+- Simpler for engineering  
+- Easier to maintain  
+- Scalable in pricing  
+- Fully usage-based  
+
+All future modules (Optimizer, Linker, etc.) must also follow the same credit model.
+
+---