docs(pricing): improve comments

Author: Ansonhkg

packages/networks/src/networks/vNaga/shared/managers/pricing-manager/getMaxPricesForNodeProduct.ts

@@ -15,6 +15,13 @@ export interface MaxPricesForNodes {
  * Ensures the total cost does not exceed userMaxPrice.
  * Operates in the order of lowest priced node to highest.
  *
+ * Example:
+ * - Selected nodes have SIGN_SESSION_KEY prices of 10 and 20.
+ * - `userMaxPrice` is 100.
+ * - Base total = 10 + 20 = 30.
+ * - Excess = 100 - 30 = 70.
+ * - Each node receives 70 / 2 = 35 extra budget, yielding 45 and 55.
+ *
  * @param nodePrices - An object where keys are node addresses and values are arrays of prices for different action types.
  * @param userMaxPrice - The maximum price the user is willing to pay to execute the request.
  * @param productId - The ID of the product to determine which price to consider.
@@ -47,14 +54,14 @@ export function getMaxPricesForNodeProduct({
     ? sortedNodes.slice(0, numRequiredNodes)
     : sortedNodes;
 
+  // Sum the unadjusted cost for the nodes we plan to use.
   let totalBaseCost = 0n;
-
-  // Calculate the base total cost without adjustments
   for (const { prices } of nodesToConsider) {
+    // Example: base total accumulates 10 + 20 = 30 for the two cheapest nodes.
     totalBaseCost += prices[productId];
   }
 
-  // Verify that we have a high enough userMaxPrice to fulfill the request
+  // Refuse to proceed if the caller's budget cannot even cover the base cost.
   if (totalBaseCost > userMaxPrice) {
     throw new MaxPriceTooLow(
       {
@@ -72,13 +79,16 @@ export function getMaxPricesForNodeProduct({
    * our request to fail if the price on some of the nodes is higher than we think it was, as long as it's not
    * drastically different than we expect it to be
    */
+  // Any remaining budget is spread across the participating nodes to
+  // provide cushion for minor pricing fluctuations. Example: 100 - 30 = 70.
   const excessBalance = userMaxPrice - totalBaseCost;
 
   // Map matching the keys from `nodePrices`, but w/ the per-node maxPrice computed based on `userMaxPrice`
   const maxPricesPerNode: { url: string; price: bigint }[] = [];
 
   for (const { url, prices } of nodesToConsider) {
-    // For now, we'll distribute the remaining balance equally across nodes
+    // Distribute the remaining budget evenly across nodes to form the max price.
+    // Example: each node receives 70 / 2 = 35, becoming 10+35 and 20+35.
     maxPricesPerNode.push({
       url,
       price: excessBalance