Add XML doc comments to pricing assembly services

Added comprehensive XML documentation to JobItemAssemblyService and
QuotePricingAssemblyService — the most complex area of the codebase.
Comments explain the three-overload pattern, seed class rationale,
powder-to-order formula and industry default fallbacks, AI prediction
override tracking, and the incoming inventory auto-creation workflow.
PricingCalculationService was already well-documented; no changes needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/PowderCoating.Application/Services/QuotePricingAssemblyService.cs

@@ -6,6 +6,20 @@ using Microsoft.Extensions.Logging;
 
 namespace PowderCoating.Application.Services;
 
+/// <summary>
+/// Orchestrates the full quote item assembly pipeline: pricing calculation, entity construction,
+/// AI prediction tracking, and automatic inventory record creation for incoming powder orders.
+///
+/// This service sits above <see cref="PricingCalculationService"/> — it knows HOW to build and
+/// persist quote entities, while PricingCalculationService knows HOW to compute dollar amounts.
+/// Keeping them separate means pricing logic can be unit-tested without any entity construction concerns.
+///
+/// Key responsibilities:
+///   - <see cref="ApplyPricingSnapshot"/>  — stamps calculated totals onto the Quote entity so the
+///     displayed price is frozen at quote time and won't change if operating costs are updated later.
+///   - <see cref="CreateQuoteItemsAsync"/> — builds QuoteItem + coats + prep services for each DTO,
+///     records AI prediction overrides, and auto-creates incoming inventory records when needed.
+/// </summary>
 public class QuotePricingAssemblyService : IQuotePricingAssemblyService
 {
     private readonly IUnitOfWork _unitOfWork;
@@ -25,6 +39,11 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         _logger = logger;
     }
 
+    /// <summary>
+    /// Writes the calculated pricing breakdown onto the <see cref="Quote"/> entity as a snapshot.
+    /// Snapshots are critical: once a quote is sent to a customer, operating cost changes must NOT
+    /// silently alter the quoted amounts — the snapshot preserves what was presented at the time.
+    /// </summary>
     public void ApplyPricingSnapshot(Quote quote, QuotePricingResult pricingResult)
     {
         ArgumentNullException.ThrowIfNull(quote);
@@ -56,6 +75,12 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         quote.Total                        = pricingResult.Total;
     }
 
+    /// <summary>
+    /// Builds and prices all <see cref="QuoteItem"/> entities from the incoming DTOs.
+    /// For each item: constructs the entity, calculates pricing, records whether the user overrode
+    /// an AI estimate, then attaches coats (including auto-creating incoming inventory entries when
+    /// the user selects a catalog powder not yet in their inventory) and prep services.
+    /// </summary>
     public async Task<IReadOnlyList<QuoteItem>> CreateQuoteItemsAsync(
         IEnumerable<CreateQuoteItemDto> itemDtos,
         int quoteId,
@@ -80,6 +105,13 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         return items;
     }
 
+    /// <summary>
+    /// Routes a single item to the correct pricing path and stamps the result onto the entity.
+    /// Priority order matches the routing table in <see cref="PricingCalculationService.CalculateQuoteItemPriceAsync"/>:
+    /// AI items → Sales items → Catalog (no coats) → full calculation engine.
+    /// Keeping pricing logic in PricingCalculationService means this method only decides WHICH
+    /// path to take, never HOW to compute the price.
+    /// </summary>
     private async Task ApplyPricingAsync(QuoteItem item, CreateQuoteItemDto itemDto, int companyId, decimal? ovenRateOverride)
     {
         if (itemDto.IsAiItem && itemDto.ManualUnitPrice.HasValue && itemDto.ManualUnitPrice.Value > 0)
@@ -127,6 +159,12 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         ApplyCalculatedPricing(item, pricing);
     }
 
+    /// <summary>
+    /// Builds <see cref="QuoteItemCoat"/> entities for a single item, including per-coat pricing.
+    /// If a coat has <c>AddAsIncoming = true</c> and references a catalog item but not an inventory
+    /// item, an incoming <see cref="InventoryItem"/> is auto-created so the shop can track the powder
+    /// order and receive it later — see <see cref="CreateIncomingInventoryItemAsync"/> for details.
+    /// </summary>
     private async Task<List<QuoteItemCoat>> BuildQuoteItemCoatsAsync(CreateQuoteItemDto itemDto, int companyId, DateTime createdAtUtc)
     {
         if (itemDto.Coats == null || itemDto.Coats.Count == 0)
@@ -158,6 +196,7 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         return coats;
     }
 
+    /// <summary>Constructs <see cref="QuoteItemPrepService"/> entities from the item DTO's prep service list.</summary>
     private static List<QuoteItemPrepService> BuildQuoteItemPrepServices(CreateQuoteItemDto itemDto, int companyId, DateTime createdAtUtc)
     {
         if (itemDto.PrepServices == null || itemDto.PrepServices.Count == 0)
@@ -175,6 +214,11 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
             .ToList();
     }
 
+    /// <summary>
+    /// Constructs a bare <see cref="QuoteItem"/> entity from the DTO — no pricing or coats yet.
+    /// Pricing is applied separately by <see cref="ApplyPricingAsync"/> to keep the construction
+    /// and calculation steps distinct and individually testable.
+    /// </summary>
     private static QuoteItem BuildQuoteItem(CreateQuoteItemDto itemDto, int quoteId, int companyId, DateTime createdAtUtc)
     {
         return new QuoteItem
@@ -204,6 +248,7 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         };
     }
 
+    /// <summary>Constructs a <see cref="QuoteItemCoat"/> entity from the coat DTO. Per-coat pricing is applied by the caller.</summary>
     private static QuoteItemCoat BuildQuoteItemCoat(CreateQuoteItemCoatDto coatDto, int companyId, DateTime createdAtUtc)
     {
         return new QuoteItemCoat
@@ -225,6 +270,10 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         };
     }
 
+    /// <summary>
+    /// Stamps the pricing result onto the quote item entity.
+    /// Broken out as a separate method because it's called from multiple branches of ApplyPricingAsync.
+    /// </summary>
     private static void ApplyCalculatedPricing(QuoteItem item, QuoteItemPricingResult pricing)
     {
         item.UnitPrice = pricing.UnitPrice;
@@ -234,6 +283,13 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         item.ItemEquipmentCost = pricing.EquipmentCost;
     }
 
+    /// <summary>
+    /// Checks whether the user changed the AI's surface area or price estimates before saving,
+    /// and sets <c>UserOverrodeEstimate = true</c> on the prediction record if they did.
+    /// This flag feeds the AI analytics reports — over time it reveals how accurate the AI is
+    /// and whether certain item types consistently need manual correction.
+    /// A tolerance of $0.01 / 0.01 sqft is used to ignore floating-point rounding noise.
+    /// </summary>
     private async Task UpdateAiPredictionOverrideAsync(CreateQuoteItemDto itemDto, decimal finalUnitPrice)
     {
         if (!itemDto.AiPredictionId.HasValue) return;
@@ -247,6 +303,23 @@ public class QuotePricingAssemblyService : IQuotePricingAssemblyService
         prediction.UpdatedAt = DateTime.UtcNow;
     }
 
+    /// <summary>
+    /// Auto-creates an "incoming" <see cref="InventoryItem"/> when a user selects a powder from the
+    /// platform catalog that doesn't yet exist in their company's inventory.
+    ///
+    /// WHY this exists: shops often quote jobs using powders they haven't ordered yet. Rather than
+    /// forcing the user to manually add the powder to inventory before quoting, we create an
+    /// IsIncoming=true record on their behalf. The shop can then receive the actual order against
+    /// this record later (updating quantity + receive date) without losing the link to the original quote.
+    ///
+    /// The AI augmentation step (LookupByUrlAsync) fills in technical specs (cure temp/time, coverage,
+    /// color families, etc.) that may be missing from the scraped catalog JSON. It is best-effort —
+    /// if it fails, the item is still created with whatever data the catalog has.
+    ///
+    /// After creation, <c>coatDto.PowderCostPerLb</c> is cleared so the pricing engine treats this
+    /// as an inventory-linked coat (not a custom powder), ensuring future repricings use the
+    /// inventory unit cost rather than the now-stale manual price from the quote form.
+    /// </summary>
     private async Task<int?> CreateIncomingInventoryItemAsync(CreateQuoteItemCoatDto coatDto, int companyId)
     {
         try