Enterprise Brokerage Commission Management

--- 
+++ 
@@ -1,189 +1,180 @@
 ```
 
-## Overview
+### Section 1: Overview
 
-The Mutual Fund Brokerage Performance and Commission Management feature provides comprehensive tracking and analysis of brokerage earnings from mutual fund transactions across different time periods, fund categories, and team members. This feature enables financial advisors to monitor their commission income, analyze performance across various dimensions, manage brokerage structures for sub-advisors, and generate detailed commission reports for business planning and compliance purposes.
+The Enterprise Brokerage Commission Management system allows financial advisors to create and manage comprehensive commission structures for their sub-broker networks. This feature enables you to define commission categories, trail percentages across multiple years, establish organizational hierarchies through branches and designations, and manage sub-broker relationships with detailed commission rules. 
 
-• Track brokerage performance across AMCs, schemes, categories, and clients with flexible date range filtering
-• Manage commission structures and brokerage slabs for sub-advisors and team members
-• Generate detailed transaction-wise commission reports with multiple breakdown options
-• Monitor team member performance and earnings distribution across the advisor hierarchy
-• Configure brokerage rates and commission structures for different fund categories and schemes
+• Create custom commission structures with different trail percentages for each year
+• Set up organizational branches and designation hierarchies for sub-broker management
+• Upload and process bulk commission rule files for multiple schemes
+• Track commission category changes with complete audit logs
+• Manage sub-broker documentation and compliance requirements
 
-## Prerequisites and Access
+### Section 2: Prerequisites and Access
 
-**Required Access:** Valid IFANOW subscription with brokerage management permissions. Admin advisors can view all team member performance; sub-advisors can only view their own performance data.
+You need an IFANOW Enterprise subscription with admin-level access to the brokerage module. Navigate to **Backoffice > Brokerage Management** to access these features. Your account must have commission structure creation permissions and sub-broker management rights.
 
-**Navigation:** Dashboard → Brokerage → Performance Analysis (for performance reports) or Dashboard → Settings → Brokerage Management (for slab configuration)
+### Section 3: How-To Steps
 
-**Required Setup:** Active mutual fund transactions, configured ARN/RIA details, and established client relationships. For sub-advisor management, brokerage slabs must be created and assigned.
+## How to Create a Commission Category Structure
 
-## How-To Steps
+Set up a new commission category with specific trail percentages for different investment types.
 
-### How to View Overall Brokerage Performance
+1. Go to **Brokerage Management > Commission Categories**
+2. Click **Add New Commission Category**
+3. Enter the **Slab Name** (e.g., "Premium Advisor Structure")
+4. Add a **Description** explaining the commission structure
+5. Set the **Commission Rate** as either percentage or basis points
+6. Click **Save Commission Category**
+7. The system creates the category and displays a confirmation message
 
-View your total brokerage earnings and performance metrics for any time period.
+The new commission category becomes available for assignment to sub-brokers and trail configurations.
 
-1. Navigate to Dashboard → Brokerage → Performance Summary
-2. Select your desired start date and end date using the date picker
-3. Choose filters for specific advisors, categories, schemes, or clients (optional)
-4. Click "Generate Report" to load performance data
-5. Review the summary showing total positive brokerage, clawback amounts, and net brokerage
-6. View the transaction count and record summary at the bottom
+## How to Configure Trail Commission Rates
 
-The system displays your total earnings breakdown and allows you to drill down into specific performance areas. Performance data updates in real-time based on your selected filters.
+Define specific trail percentages for different years and fund categories within a commission structure.
 
-### How to Analyze AMC-Wise Brokerage Performance
+1. Select an existing commission category from the list
+2. Click **Configure Trail Rates**
+3. Choose the **Fund Category** (equity, debt, hybrid, etc.)
+4. Set **First Year Trail** percentage
+5. Set **Second Year Trail** percentage  
+6. Set **Third Year Trail** percentage
+7. Set **Fourth Year Trail** percentage
+8. Set **B30 Trail** percentage for investments beyond 30 days
+9. Set **Others** percentage for additional categories
+10. Click **Save Trail Configuration**
 
-Break down your earnings by Asset Management Company to identify top-performing fund houses.
+The system validates all percentages and saves the trail structure. Changes are logged for audit purposes.
 
-1. Go to Dashboard → Brokerage → Performance Analysis
-2. Select "AMC-Wise" from the analysis type dropdown
-3. Set your date range and any additional filters
-4. Click "Analyze Performance"
-5. Review the ranked list of AMCs by total brokerage amount
-6. Click on any AMC name to see detailed scheme-level breakdown
+## How to Create Branch Hierarchy
 
-Results are automatically sorted by highest brokerage amount first. Use this analysis to identify which fund houses generate the most commission income for your practice.
+Establish organizational branch structure for sub-broker management.
 
-### How to Generate Scheme-Wise Performance Reports
+1. Navigate to **Brokerage Management > Branch Management**
+2. Click **Add New Branch**
+3. Enter **Branch Name** and **Branch Code**
+4. Select **Branch Level** (the system suggests the next available level)
+5. Choose **Parent Branch** if creating a sub-branch
+6. Click **Save Branch**
 
-Analyze performance at the individual mutual fund scheme level for detailed insights.
+The branch appears in the hierarchy view and becomes available for sub-broker assignments. Higher-level branches can contain multiple sub-branches.
 
-1. Navigate to Dashboard → Brokerage → Performance Analysis
-2. Choose "Scheme-Wise" from the report type
-3. Apply date range and optional filters for specific categories or AMCs
-4. Select "Generate Report"
-5. Review the detailed scheme listing with brokerage amounts
-6. Use the search function to find specific schemes quickly
+## How to Set Up Designation Levels
 
-The report shows all schemes ranked by commission earned, helping you identify your most profitable fund recommendations.
+Create designation hierarchy to define roles and reporting structures.
 
-### How to View Client-Wise Commission Breakdown
+1. Go to **Brokerage Management > Designations**
+2. Click **Add New Designation**
+3. Enter **Designation Name** (e.g., "Regional Manager", "Team Lead")
+4. Set **Designation Level** (system suggests next level)
+5. Click **Save Designation**
 
-See which clients generate the most brokerage income for your practice.
+The designation becomes available when adding sub-brokers and determines reporting relationships.
 
-1. Access Dashboard → Brokerage → Client Analysis
-2. Set your analysis period using date filters
-3. Choose pagination settings (default 20 clients per page)
-4. Click "Load Client Performance"
-5. Browse through client rankings by brokerage amount
-6. Use the search feature to find specific clients
+## How to Add a Sub-Broker
 
-Client data includes both individual and family member transactions. This helps identify your highest-value relationships for business development focus.
+Register a new sub-broker with complete profile and commission assignment.
 
-### How to Create Brokerage Slabs for Sub-Advisors
+1. Navigate to **Sub-Broker Management > Add Sub-Broker**
+2. Select the **Team Member** from your advisor list
+3. Choose **Reporting Manager** from existing sub-brokers
+4. Select **Branch** and **Designation** from dropdown menus
+5. Choose **Commission Category** for this sub-broker
+6. Enter **EUIN** and **Sub-Broker Code** if applicable
+7. Add **GSTIN** for tax purposes
+8. Select **Bank Details** and **Address Information**
+9. Choose applicable **Commission Rules** from available structures
+10. Add **ARN/RIA Numbers** for compliance
+11. Set **Start Date** and **Expiry Date** for ARN validity
+12. Click **Save Sub-Broker**
 
-Set up commission structures for your team members with customized rate slabs.
+The system validates all information, checks for duplicates, and creates the sub-broker profile with proper hierarchy mapping.
 
-1. Go to Dashboard → Settings → Brokerage Management
-2. Click "Create New Slab"
-3. Enter a descriptive slab name
-4. Define date ranges for when this slab applies
-5. Choose between flat rate or AUM-based structure
-6. Set commission percentages for different trail periods (1st year, 2nd year, etc.)
-7. Configure category-specific rates if needed
-8. Save the slab configuration
+## How to Upload Bulk Commission Rules
 
-**Warning:** Once a slab is assigned to sub-advisors, modifications may affect their historical commission calculations.
+Process multiple scheme-wise commission rules through file upload.
 
-### How to Assign Sub-Advisors to Brokerage Slabs
+1. Go to **Commission Rules > Bulk Upload**
+2. Select the **Rule Master** to apply rules to
+3. Click **Get Upload URL** and choose Excel file type
+4. Upload your commission rules file using the provided URL
+5. Enter **File Description** and click **Process File**
+6. Monitor the **Processing Status** on the upload summary page
+7. Review **Failed Records** if any processing errors occur
+8. Click **Approve Upload** once validation is complete
 
-Connect team members to their appropriate commission structures.
+The system processes each scheme individually and provides detailed success/failure reporting.
 
-1. Navigate to Dashboard → Team → Sub-Broker Management
-2. Select the advisor you want to assign a slab to
-3. Choose their appropriate brokerage slab from the dropdown
-4. Confirm the assignment
-5. Review the advisor's client count and expected impact
+## How to Manage Sub-Broker Documents
 
-The system immediately applies the new slab to future transactions. Historical transactions retain their original commission calculations.
+Upload and maintain compliance documents for sub-brokers.
 
-### How to Generate Transaction-Level Commission Reports
+1. Navigate to **Sub-Broker Management > Documents**
+2. Select the **Sub-Broker** from the list
+3. Click **Add Document**
+4. Choose **Document Type** from available options
+5. Upload the document file
+6. Enter **Document Description**
+7. Click **Save Document**
 
-Create detailed reports showing individual transaction commissions.
+Documents are stored securely and can be updated or deleted as needed for compliance tracking.
 
-1. Access Dashboard → Brokerage → Transaction Reports
-2. Set your date range and transaction limit (maximum 100,000 records)
-3. Apply filters for specific advisors, AMCs, schemes, or clients
-4. Select "Generate Detailed Report"
-5. Review transaction-by-transaction commission data
-6. Export the report if needed for external analysis
+### Section 4: Rules and Limits
 
-Each transaction shows the original commission and any adjusted amounts based on sub-advisor slab rates.
+• Commission categories cannot be deleted if they're assigned to active sub-brokers
+• Trail percentages must be non-negative values and can be zero
+• Branch and designation levels must be sequential starting from 1
+• Sub-broker codes must be unique within your organization
+• GSTIN must be exactly 15 characters when provided
+• ARN/RIA mappings are required for commission rule creation
+• File uploads only accept Excel (.xlsx) format
+• Sub-brokers cannot report to someone in their own hierarchy (prevents loops)
+• Only active commission structures can be assigned to sub-brokers
+• Branch and designation masters cannot be deleted if assigned to sub-brokers
+• All commission changes create audit log entries automatically
+• File processing happens asynchronously and may take several minutes
+• Document uploads require valid file extensions and size limits apply
 
-### How to View Team Member Performance Summary
+### Section 5: Common Questions
 
-Monitor the brokerage performance of all sub-advisors in your organization.
+**Q: Can I modify a commission structure after assigning it to sub-brokers?**
+A: Yes, you can edit commission categories and trail rates. The system creates a backup log of the previous structure and applies changes to future calculations while preserving historical data.
 
-1. Go to Dashboard → Team → Performance Overview
-2. Select the performance period
-3. Choose specific team members or view all
-4. Click "Load Team Performance"
-5. Review each team member's total earnings, transaction count, and admin earnings
-6. Compare performance across team members
+**Q: What happens if I change a sub-broker's reporting relationship?**
+A: The system updates the entire hierarchy automatically, ensuring all upstream and downstream relationships remain valid. You cannot create circular reporting relationships.
 
-This view helps identify top-performing team members and areas where additional training or support may be needed.
+**Q: How do I know if my bulk upload file was processed successfully?**
+A: Check the upload status page which shows processing progress, total records processed, successful entries, and any failed records with specific error messages.
 
-## Rules and Limits
+**Q: Can I have the same person as both a regular team member and a sub-broker?**
+A: No, each team member can only have one role. If someone is already a team member, you must assign them sub-broker status rather than creating a duplicate entry.
 
-• Maximum 100,000 transactions can be included in detailed transaction reports
-• Brokerage slabs cannot be deleted if they are currently assigned to active sub-advisors
-• Commission calculations only apply to transactions occurring after slab assignment dates
-• Exception transactions can be manually reassigned to different advisors for commission purposes
-• Date ranges for performance reports cannot exceed system-defined limits for optimal performance
-• Sub-advisor commission rates are calculated as percentages of the original admin brokerage amount
-• Clawback amounts are automatically calculated as absolute values and subtracted from positive earnings
-• AUM-based slab structures require minimum and maximum AUM thresholds to be defined
-• Flat rate structures apply the same commission percentage regardless of AUM levels
-• Category-specific rates override scheme-specific rates when both are defined
-• Scheme-specific rates take precedence over sub-category rates in commission calculations
+**Q: What's the difference between basis points and percentage in commission structures?**
+A: Basis points are hundredths of a percent (100 basis points = 1%), commonly used in financial calculations. Choose the format that matches your commission agreements.
 
-## Common Questions
+### Section 6: Troubleshooting
 
-**Q: Can I change a brokerage slab after assigning it to a sub-advisor?**
-A: Yes, you can modify slab rates, but changes only apply to new transactions going forward. Historical commissions remain unchanged to maintain accuracy.
+**Problem:** Cannot delete commission category
+**Cause:** The commission category is currently assigned to active sub-brokers
+**Fix:** First remove the category assignment from all sub-brokers, then delete the category
 
-**Q: Why don't I see some of my recent transactions in the performance reports?**
-A: Performance reports may have a slight delay as transaction data is processed and commission calculations are completed. Very recent transactions may appear in the next reporting cycle.
+**Problem:** File upload fails during processing  
+**Cause:** Excel file contains invalid scheme names, missing required columns, or formatting errors
+**Fix:** Download the failed records report, correct the data issues, and re-upload the corrected file
 
-**Q: How are clawback amounts handled in my performance calculations?**
-A: Clawback amounts are automatically identified as negative brokerage transactions and subtracted from your total positive earnings to show your true net commission income.
+**Problem:** Sub-broker hierarchy update rejected
+**Cause:** The new reporting relationship would create a circular hierarchy loop
+**Fix:** Choose a different reporting manager who is not in the sub-broker's downstream hierarchy
 
-**Q: Can I create different commission rates for different fund categories?**
-A: Yes, brokerage slabs support category-specific, sub-category-specific, and even scheme-specific commission rates, allowing you to customize earnings based on fund types.
+**Problem:** Commission trail configuration won't save
+**Cause:** One or more trail percentage fields contain negative values or invalid characters
+**Fix:** Ensure all percentage fields contain only positive numbers or zero, using decimal format (e.g., 1.25 for 1.25%)
 
-**Q: What happens if I have overlapping date ranges in my brokerage slabs?**
-A: The system uses the most specific applicable rate for each transaction. Scheme-specific rates override category rates, and newer slabs take precedence over older ones for the same date periods.
+**Problem:** Document upload appears successful but document not visible
+**Cause:** Document type was not properly selected or file upload to cloud storage failed
+**Fix:** Verify document type selection and try uploading again, ensuring stable internet connection
 
-## Troubleshooting
+### Section 7: Related Features
 
-**Problem:** Performance report shows "No data found" even though I have active transactions
-**Cause:** Selected date range may not include transaction periods, or applied filters are too restrictive
-**Fix:** Expand your date range and remove any restrictive filters, then regenerate the report
-
-**Problem:** Sub-advisor commission calculations appear incorrect
-**Cause:** Brokerage slab may not have been active during the transaction period, or slab rates are configured incorrectly
-**Fix:** Verify the slab's date range covers the transaction dates and check that commission percentages are set correctly for the applicable fund categories
-
-**Problem:** Cannot delete a brokerage slab
-**Cause:** The slab is currently assigned to one or more active sub-advisors
-**Fix:** Reassign all sub-advisors to different slabs first, then attempt to delete the unused slab
-
-**Problem:** Transaction report exceeds the maximum limit error
-**Cause:** Your date range and filters include more than 100,000 transactions
-**Fix:** Narrow your date range or apply more specific filters to reduce the transaction count, then generate multiple smaller reports if needed
-
-**Problem:** Team member performance shows zero earnings despite having transactions
-**Cause:** The team member may not have a brokerage slab assigned, or their slab has zero commission rates configured
-**Fix:** Ensure the team member has an active brokerage slab assignment with properly configured commission rates
-
-## Related Features
-
-This feature integrates with several other IFANOW modules:
-• **Advisor Management** - for team hierarchy and sub-advisor relationships
-• **Mutual Fund Transactions** - for underlying transaction data and commission calculations  
-• **Client Management** - for client-wise performance analysis and investor identification
-• **Portfolio Management** - for AUM calculations used in AUM-based brokerage slabs
-• **Reporting Engine** - for generating and exporting detailed commission reports
-• **ARN/RIA Management** - for regulatory compliance and proper commission attribution
+This feature integrates with **Team Member Management** for advisor assignments and **Master Data Management** for fund categories and AMC information. Commission calculations connect to **Transaction Processing** and **Portfolio Management** modules. The hierarchy system links with **Role-Based Access Control** for permission management. Document storage utilizes **File Management Services** for secure cloud storage. Audit logging connects with **Compliance Reporting** features for regulatory tracking.