feat: enhance agent settlement features and improve data access controls

- Added new section in AGENTS.md detailing learned workspace facts for better understanding of settlement processes.
- Updated AgentNodeDestroyController to remove unnecessary checks for admin users.
- Enhanced AgentSettlement controllers to assert permissions for finance adjustments and bill operations.
- Improved query scopes in AgentSettlement services to ensure proper data access based on admin roles.
- Refactored methods in SettlementPartyEnrichment for better bill row enrichment and data handling.
- Introduced new methods in AdminAgentSettlementScope for managing agent node visibility and finance adjustments.

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementBillShowController.php

@@ -3,6 +3,7 @@
 namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
 
 use App\Http\Controllers\Controller;
+use App\Services\AgentSettlement\SettlementBillDownlineShareBuilder;
 use App\Services\AgentSettlement\SettlementPartyEnrichment;
 use App\Support\AdminAgentSettlementScope;
 use App\Support\ApiResponse;
@@ -14,6 +15,7 @@ final class AgentSettlementBillShowController extends Controller
 {
     public function __construct(
         private readonly SettlementPartyEnrichment $partyEnrichment,
+        private readonly SettlementBillDownlineShareBuilder $downlineShareBuilder,
     ) {}
 
     public function __invoke(Request $request, int $settlement_bill): JsonResponse
@@ -77,11 +79,12 @@ final class AgentSettlementBillShowController extends Controller
         }
 
         return ApiResponse::success([
-            'bill' => $bill,
+            'bill' => $this->partyEnrichment->enrichBillRow($bill),
             'payments' => $payments,
             'rebate_allocations' => $rebateAllocations,
             'adjustments' => $adjustments,
             'tier_edge' => $tierSettlements,
+            'downline_shares' => $this->downlineShareBuilder->forBill($bill),
         ]);
     }
 }